.\" format with nroff|troff|groff -man
.nr mI 0
.de H1
.if \\n(mI!=0 \{
.nr mI 0
.RE
.\}
.TP
\fB\\$1\fP
..
.de H3
.if \\n(mI=0 \{
.nr mI 1
.RS
.\}
.TP
\fB     \\$1\fP
..
.de OP
.if \\n(mI!=0 \{
.nr mI 0
.RE
.\}
.ie !'\\$1'-' \{
.ds mO \\fB\\-\\$1\\fP
.ds mS ,\\0
.\}
.el \{
.ds mO \\&
.ds mS \\&
.\}
.ie '\\$2'-' \{
.if !'\\$4'-' .as mO \\0\\fI\\$4\\fP
.\}
.el \{
.as mO \\*(mS\\fB\\-\\-\\$2\\fP
.if !'\\$4'-' .as mO =\\fI\\$4\\fP
.\}
.TP
\\*(mO
..
.de FN
.if \\n(mI!=0 \{
.nr mI 0
.RE
.\}
.TP
\\$1 \\$2
..
.TH iffe 1
.SH NAME
iffe - host C compilation environment feature probe
.SH SYNOPSIS
\fBiffe\fP\ [\ \fIoptions\fP\ ]\ [\ -\ ]\
[\ file.iffe\ |\ statement\ [\ :\ statement\ ...\ ]\ ]
.SH DESCRIPTION
\fBiffe\fP is a command interpreter that probes the host C compilation environment for
features. A feature is any file, option or symbol that controls or is controlled by the C
compiler. \fBiffe\fP tests features by generating and compiling C programs and observing
the behavior of the C compiler and generated programs.
.PP
\fBiffe\fP statements are line oriented. Statements may appear in the operand list with
the \fB:\fP operand or \fBnewline\fP as the line delimiter. The standard input is read if
there are no command line statements or if \fIfile\fP\fB.iffe\fP is omitted.
.PP
Though similar in concept to \fBautoconfig\fP(1) and \fBconfig\fP(1), there are
fundamental differences. The latter tend to generate global headers accessed by all
components in a package, whereas \fBiffe\fP is aimed at localized, self contained feature
testing.
.PP
Output is generated in \fBFEATURE/\fP\fItest\fP by default, where \fItest\fP is the base
name of \fIfile\fP\fB.iffe\fP or the \fBiffe\fP \fBrun\fP command file operand. Output is
first generated in a temporary file; the output file is updated if it does not exist or
if the temporary file is different. If the first operand is \fB-\fP then the output is
written to the standard output and no update checks are done.
.PP
Files with suffixes \fB.iffe\fP and \fB.iff\fP are assumed to contain \fBiffe\fP
statements.
.SH OPTIONS
.OP a all flag -
Define failed test macros \fB0\fP. By default only successful test macros are defined
\fB1\fP.
.OP c cc string C-compiler-name\ [C-compiler-flags\ ...]
Sets the C compiler name and flags to be used in the feature tests.
.OP C config flag -
Generate \fBconfig\fP(1) style \fIHAVE_\fP* macro names. This implies \fB--undef\fP.
Since \fBconfig\fP(1) has inconsistent naming conventions, the \fBexp\fP command may be
needed to translate from the (consistent) \fBiffe\fP names. Unless otherwise noted a
\fBconfig\fP macro name is the \fBiffe\fP macro name prefixed with \fBHAVE\fP and
converted to upper case. \fB--config\fP is set by default if the command arguments
contain a \fBrun\fP command on an input file with the base name \fBconfig\fP.
.OP d debug number level
Sets the debug level. Level 0 inhibits most error messages, level 1 shows compiler
messages, and level 2 traces internal \fBiffe\fP \fBsh\fP(1) actions.
.OP i input string file
Sets the input file name to \fIfile\fP, which must contain \fBiffe\fP statements.
.OP o output string file
Sets the output file name to \fIfile\fP.
.OP e package string name
Sets the \fBproto\fP(1) package name to \fIname\fP.
.OP p prototyped flag -
Emits \fB#pragma prototyped\fP at the top of the output file. See \fBproto\fP(1).
.OP P pragma string text
Emits \fB#pragma\fP \fItext\fP at the top of the output file.
.OP s shell string shell-path
Sets the internal shell name to \fIshell-path\fP. Used for debugging Bourne shell
compatibility (otherwise \fBiffe\fP uses \fIksh\fP constructs if available).
.OP S static string flags
Sets the C compiler flags that force static linking. If not set then \fBiffe\fP probes
the compiler to determine the flags. \fBiffe\fP must use static linking (no dlls) because
on some systems missing library symbols are only detected when referenced at runtime from
dynamically linked executables.
.OP u undef flag -
\fB#undef\fP failed test macros. By default only successful test macros are defined
\fB1\fP.
.OP v verbose flag -
Produce a message line on the standard error for each test as it is performed.
.SH SYNTAX
\fBiffe\fP input consists of a sequence of statement lines. Statements that span more
than one line contain \fIbegin\fP\fB{\fP as the last operand (where \fIbegin\fP is
command specific) and zero or more data lines terminated by a line containing \fB}end\fP
as the first operand. The statements syntax is: \fIop\fP[,\fIop\fP...]
[\fIarg\fP[,\fIarg\fP...]] [\fIprereq\fP ...] [\fIbegin\fP{ ... |\fBend\fP ...]
[= [\fIdefault\fP]]. \fIop\fPs and \fIarg\fPs may be combined, separated by commas, to
perform a set of operations on a set of arguments.
.PP
\fIprereq\fPs are used when applying the features tests and may be combinations of:
.H1 compiler\ options
\fB-D\fP*, \fB-L\fP*, etc.
.H1 library\ references
\fB-l\fP*, *\fB.a\fP, etc. \fB_LIB_\fP\fIname\fP is defined to be 1 if \fB-l\fP\fIname\fP
is a library.
.H1 header\ references
*\fB.h\fP. \fI_dir_name\fP is defined to be 1 if \fIdir/name\fP\fB.h\fP is a header, or
if \fIdir\fP is omitted, \fB_hdr_\fP\fIname\fP is defined to be 1 if \fIname\fP\fB.h\fP
is a header.
.H1 -
Prereq grouping mark; prereqs before the first \fB-\fP are passed to all feature tests.
Subsequent groups are attempted in left-to-right order until the first successful group
is found.
.PP
\fIbegin\fP\fB{\fP ... \fB}end\fP delimit multiline code blocks that override or augment
the default code provided by \fBiffe\fP. User supplied code blocks should be compatible
with the K&R, ANSI, and C++ C language dialects for maximal portability. In addition to
all macro definitions generated by previous tests, all generated code contains the
following at the top to hide dialect differences:
.H1 #if\ defined(__STDC__)\ ||\ defined(__cplusplus)\ ||\ defined(c_plusplus)
.H1 #define\ _STD_\ 1
.H1 #define\ _ARG_(x)\ x
.H1 #define\ _VOID_\ void
.H1 #else
.H1 #define\ _STD_\ 0
.H1 #define\ _ARG_(x)\ ()
.H1 #define\ _VOID_\ char
.H1 #endif
.H1 #if\ defined(__cplusplus)
.H1 #define\ _BEGIN_EXTERNS_\ extern\ "C"\ {
.H1 #define\ _END_EXTERNS_\ }
.H1 #else
.H1 #define\ _BEGIN_EXTERNS_
.H1 #define\ _END_EXTERNS_
.H1 #endif
.H1 #define\ _NIL_(x)\ ((x)0)
.PP
= \fIdefault\fP may be specified for the \fBkey\fP, \fBlib\fP, \fBmth\fP and \fBtyp\fP
commands. If the test fails for \fIarg\fP then \fB#define\fP \fIarg\fP \fIdefault\fP is
emitted. \fBkey\fP accepts multiple \fB= \fP\fIdefault\fP values; the first valid one is
used.
.PP
Each test statement generates a portion of a C language header that contains macro
defintions, comments, and other text corresponding to the feature test commands.
\fB#ifndef _def_\fP\fIname\fP\fB_\fP\fIdirectory\fP ... \fB#endif\fP guards the generated
header from multiple \fB#include\fPs, where \fIname\fP is determined by either the
\fBrun\fP command input file name if any, or the first \fIop\fP of the first command, and
\fIdirectory\fP is the basname component of either the \fBrun\fP command file, if any, or
the current working directory. The output file name is determined in this order:
.H1 -
If the first command line operand is \fB-\fP then the output is written to the standard
output.
.H1 --output=file
Output is \fIfile\fP.
.H1 set\ out\ file
Output is \fIfile\fP.
.H1 [run]\ [directory/]base[.suffix]
Output is \fBFEATURE/\fP\fIbase\fP.
.PP
Generated \fBiffe\fP headers are often referenced in C source as: \fB#include
"FEATURE/\fP\fIfile\fP". The \fBnmake\fP(1) base rules contain metarules for generating
\fBFEATURE/\fP\fIfile\fP from \fBfeatures/\fP\fIfile\fP[\fIsuffix\fP], where \fIsuffix\fP
may be omitted, \fB.c\fP, or \fB.sh\fP (see the \fBrun\fP command below). Because
\fB#include\fP prerequisites are automatically detected, \fBnmake\fP(1) ensures that all
prerequisite \fBiffe\fP headers are generated before compilation. Note that the
directories are deliberately named \fBFEATURE\fP and \fBfeatures\fP to keep
case-insensitive file systems happy.
.PP
The feature test commands are:
.H1 #\ comment
Comment line - ignored.
.H1 cmd\ name
Defines \fB_cmd_\fP\fIname\fP if \fIname\fP is an executable in one of the standard
system directories (\fB/bin, /etc, /usr/bin, /usr/etc, /usr/ucb\fP).
\fB_\fP\fIdirectory\fP\fB_\fP\fIname\fP is defined for \fIdirectory\fP in which
\fIname\fP is found (with \fB/\fP translated to \fB_\fP).
.H1 dat\ name
Defines \fB_dat_\fP\fIname\fP if \fIname\fP is a data symbol in the default libraries.
.H1 def\ name
Equivalent to \fBcmd,dat,hdr,key,lib,mth,sys,typ\fP \fIname\fP.
.H1 exp\ name\ expression
If \fIexpression\fP is a "..." string then \fIname\fP is defined to be the string, else
if the \fBexpr\fP(1) evaluation of \fIexpression\fP is not 0 then \fIname\fP is defined
to be 1, otherwise \fIname\fP is defined to be 0. Identifiers in \fIexpression\fP may be
previously defined names from other \fBiffe\fP commands; undefined names evaluate to 0.
.H1 hdr\ name
Defines \fB_hdr_\fP\fIname\fP if the header \fB<\fP\fIname\fP\fB.h>\fP exists. The
\fB--config\fP macro name is \fBHAVE_\fP\fINAME\fP\fB_H\fP.
.H1 iff\ name
The generated header \fB#ifndef-#endif\fP macro guard is \fB_\fP\fIname\fP\fB_H\fP.
.H1 key\ name
Defines \fB_key_\fP\fIname\fP if \fIname\fP is a reserved word (keyword).
.H1 lcl\ name
Generates a \fB#include\fP statement for the local version of either the header
\fB<\fP\fIname\fP\fB.h>\fP if it exists or the header \fB<sys/\fP\fIname\fP\fB.h>\fP if
it exists. Defines \fB_lcl_\fP\fIname\fP on success. The \fB--config\fP macro name is
\fBHAVE_\fP\fINAME\fP\fB_H\fP.
.H1 lib\ name
Defines \fB_lib_\fP\fIname\fP if \fIname\fP is an external symbol in the default
libraries.
.H1 mac\ name
Defines \fB_mac_\fP\fIname\fP if \fIname\fP is a macro.
.H1 mem\ struct.member
Defines \fB_mem_\fP\fImember\fP\fB_\fP\fIstruct\fP if \fImember\fP is a member of the
structure \fIstruct\fP.
.H1 mth\ name
Defines \fB_mth_\fP\fIname\fP if \fIname\fP is an external symbol in the math library.
.H1 nop\ name
If this is the first command then \fIname\fP may be used to name the output file and/or
the output header guard macro. Otherwise this command is ignored.
.H1 npt\ name
Defines \fB_npt_\fP\fIname\fP if the \fIname\fP symbol requires a prototype. The
\fB--config\fP macro name is \fB\fP\fINAME\fP\fB_DECLARED\fP with the opposite sense.
.H1 num\ name
Defines \fB_num_\fP\fIname\fP if \fIname\fP is a numeric constant \fIenum\fP or
\fImacro\fP.
.H1 one\ header\ ...
Generates a \fB#include\fP statement for the first header found in the \fIheader\fP list.
.H1 pth\ file\ [\ dir\ ...\ |\ {\ g1\ -\ ...\ -\ gn\ }\ |\ <\ pkg\ [ver\ ...]\ >\ ]
Defines \fB_pth_\fP\fIfile\fP, with embedded \fB/\fP chars translated to \fB_\fP, to the
path of the first instance of \fIfile\fP in the \fIdir\fP directories. \fB{\fP ...
\fB}\fP forms a directory list from the cross-product of \fB-\fP separated directory
groups \fIg1\fP ... \fIgn\fP. < ... > forms a directory list for the package \fIpkg\fP
with optional versions. The \fB--config\fP macro name is \fINAME\fP\fB_PATH\fP.
.H1 run\ file
Runs the tests in \fIfile\fP based on the \fIfile\fP suffix:
.H2 .c
\fIfile\fP is compiled and executed and the output is copied to the \fBiffe\fP output
file.
.H2 .sh
\fIfile\fP is executed as a shell script and the output is copied to the \fBiffe\fP
output file.
.H2 .iffe\ or\ no\ suffix
\fIfile\fP contains \fBiffe\fP statements.
.H1 set\ option\ value
Sets option values. The options are described above.
.H1 siz\ name
Defines \fB_siz_\fP\fIname\fP to be \fBsizeof\fP(\fIname\fP) if \fIname\fP is a type in
any of \fB<sys/types.h>, <times.h>, <stddef.h>, <stdlib.h>\fP. Any \fB.\fP characters in
\fIname\fP are translated to space before testing and are translated to \fB_\fP in the
output macro name.
.H1 sym\ name
Defines \fB_ary_\fP\fIname\fP if \fIname\fP is an array, \fB_fun_\fP\fIname\fP if
\fIname\fP is a function pointer, \fB_ptr_\fP\fIname\fP if \fIname\fP is a pointer, or
\fB_reg_\fP\fIname\fP if \fIname\fP is a scalar. In most cases \fIname\fP is part of a
macro expansion.
.H1 sys\ name
Defines \fB_sys_\fP\fIname\fP if the header \fB<sys/\fP\fIname\fP\fB.h>\fP exists. The
\fB--config\fP macro name is \fBHAVE_SYS_\fP\fINAME\fP\fB_H\fP.
.H1 tst\ name
A user defined test on name. A source block must be supplied. Defines \fB_\fP\fIname\fP
on success.
.H1 typ\ name
Defines \fB_typ_\fP\fIname\fP if \fIname\fP is a type in any of \fB<sys/types.h>,
<times.h>, <stddef.h>, <stdlib.h>\fP. Any \fB.\fP characters in \fIname\fP are translated
to space before testing and are translated to \fB_\fP in the output macro name.
.H1 val\ name
The output of \fBecho\fP \fIname\fP is written to the output file.
.PP
Code block names may be prefixed by \fBno\fP to invert the test sense. The block names
are:
.H1 cat
The block is copied to the output file.
.H1 compile
The block is compiled (\fBcc -c\fP).
.H1 execute
The block is compiled, linked, and executed. \fB0\fP exit status means success.
.H1 fail
If the test fails then the block text evaluated by \fBsh\fP(1).
.H1 link
The block is compiled and linked (\fBcc -o\fP).
.H1 macro
The block is preprocessed (\fBcc -E\fP) and text bracketed by \fB<<\fP ... \fB>>\fP is
copied to the output file.
.H1 menu
Not implemented.
.H1 no
If the test fails then the block text is copied to the output file.
.H1 note
If the test succeeds then the block is copied to the output as a \fB/*\fP ... \fB*/\fP
comment.
.H1 output
The block is compiled, linked, and executed, and the output is copied to the output file.
.H1 pass
If the test succeeds then the block text evaluated by \fBsh\fP(1).
.H1 preprocess
The block is preprocessed (\fBcc -E\fP).
.H1 prompt
Not implemented.
.H1 run
The block is executed as a shell script and the output is copied to the output file.
Succesful test macros are also defined as shell variables with value \fB1\fP and are
available within the block. Likewise, failed test macros are defined as shell variables
with value \fB0\fP.
.H1 yes
If the test succeeds then the block text is copied to the output file.
.SH SEE\ ALSO
\fBautoconfig\fP(1), \fBconfig\fP(1), \fBnmake\fP(1), \fBproto\fP(1), \fBsh\fP(1)
.SH IMPLEMENTATION
.H1 version
iffe (AT&T Labs Research) 2000-03-17
.H1 author
Glenn Fowler <gsf@research.att.com>
.H1 author
Phong Vo <kpv@research.att.com>
.H1 copyright
Copyright (c) 1994-2000 AT&T Corp.
.H1 license
http://www.research.att.com/sw/license/ast-open.html
